README LINUX

   1 -*-text-*---------------------------------------------------------------
   2 supercollider 3 for linux
   3 ------------------------------------------------------------------------
   4 $Id$
   5 ------------------------------------------------------------------------
   6
   7 ------------------------------------------------------------------------
   8 intro
   9 ------------------------------------------------------------------------
  10
  11 SuperCollider is a synthesis engine (scsynth) and programming language
  12 (sclang), originally Mac-based but now very widely used on Linux
  13 (since Stefan Kersten ported the code in 2003). SuperCollider is free
  14 software under the GPL - its main homepage is at
  15
  16    http://supercollider.sourceforge.net
  17
  18 to get further information on supercollider usage or development, you
  19 might consider subscribing to the mailing lists
  20
  21   http://www.beast.bham.ac.uk/research/sc_mailing_lists.shtml
  22
  23 ------------------------------------------------------------------------
  24 build requirements
  25 (most of these will be available in your linux distribution as packages )
  26 ------------------------------------------------------------------------
  27
  28  * gcc >= 3.0
  29    http://www.gnu.org/software/gcc/
  30    gcc versions < 3.0 are missing some required c++ features
  31
  32  * jack and libjack
  33    http://jackit.sourceforge.net/
  34    jack audio connection kit
  35
  36  * libsndfile >= 1.0
  37    http://www.mega-nerd.com/libsndfile/
  38    _the_ soundfile i/o library
  39
  40  * pkg-config >= 0.14.0
  41    http://www.freedesktop.org/software/pkgconfig/
  42    facilitates checking for installed packages when compiling from
  43    source
  44
  45  * scons >= 0.96
  46    http://www.scons.org/
  47    configuration and build tool based on python
  48
  49  * fftw >= 3.0
  50    http://www.fftw.org/
  51    fast FFT transform library (for frequency-domain analysis,
  52                                         phase-vocoder effects)
  53
  54 ------------------------------------------------------------------------
  55 build requirements (optional features)
  56 (most of these will be available in your linux distribution as packages )
  57 ------------------------------------------------------------------------
  58
  59  * alsa
  60    http://www.alsa-project.org/
  61    advanced linux sound architecture drivers and library, for sclang's
  62    MIDI interface
  63
  64  * libreadline >= 5
  65    http://savannah.gnu.org/projects/readline
  66    provides convenient CLI interface for sclang
  67    (if unavailable, set READLINE=0 as an argument to scons)
  68
  69  * libhowl (obsolete)
  70    http://www.porchdogsoft.com/products/howl/
  71    zeroconf service dicovery implementation
  72
  73  * libavahi-client
  74    http://www.avahi.org/
  75    a more powerful zeroconf service discovery implementation
  76
  77  * linux kernel >= 2.6
  78    http://www.kernel.org/
  79    for sclang's linux input device (LID) interface
  80
  81  * for scel: the Emacs interface see the README in the directory
  82    `editors/scel'
  83
  84  * for sced: the gedit interface see the README in the directory
  85    `editors/sced'
  86
  87  * for scvim: the vim interface see the README in the directory
  88    `editors/scvim'
  89
  90
  91 ------------------------------------------------------------------------
  92 build requirements (debian users)
  93 ------------------------------------------------------------------------
  94
  95 on debian (unstable) you can install the following packages and be set
  96 for building supercollider:
  97
  98    build-essential
  99    libjack0.100.0-dev
 100    libsndfile1-dev
 101    libasound2-dev
 102    libavahi-client-dev
 103    libicu-dev
 104    libreadline6-dev
 105    libfftw3-dev
 106    libxt-dev
 107    pkg-config
 108    scons
 109
 110 ------------------------------------------------------------------------
 111 building
 112 ------------------------------------------------------------------------
 113
 114 building with scons is not really different from building with
 115 autoconf, automake and related tools.
 116
 117    $ scons -H
 118
 119 gives an overview of scons options.
 120
 121    $ scons -h
 122
 123 lists package specific options variables and their default values.
 124 (Note: some options allow to disable the dependencies on fftw and on
 125 libsndfile, but those dependencies should be considered compulsory for
 126 most standard setups since they provide much core sc functionality.)
 127
 128 options can be set on the command line
 129
 130    $ scons VARIABLE=VALUE
 131
 132 and are cached in a file called scache.conf (which can be edited with
 133 your favorite editor) for use in the next scons invocation.
 134
 135 in order to build the whole package, call scons without arguments
 136 (apart from option variables). in order to install the package, call
 137 scons with the `install' target:
 138
 139    $ scons install
 140
 141 any target (including `install') can be cleaned with the `-c' option
 142 to scons; note that cleaning the `install' target also removes locally
 143 built files.
 144
 145 The option SCEL installs the emacs editor. For the sced and scvim editors,
 146 please use the scons scripts in their respective directories (in editors/).
 147
 148 ------------------------------------------------------------------------
 149 Building a Debian package
 150 ------------------------------------------------------------------------
 151
 152 In our SVN we have debian packaging rules. These were designed on Ubuntu
 153 but we believe they should work on most common debian systems - please
 154 let us know if you have any issues with this way of building:
 155
 156   cd SuperCollider3    # (or wherever your SC source is)
 157   svn co https://supercollider.svn.sourceforge.net/svnroot/supercollider/packages/ubuntu/ debian
 158   debuild
 159
 160 Eventually, some .deb packages will be put in the parent folder, and can
 161 then be installed just like any other Debian package. For example:
 162
 163   dpkg -i ../supercollider*.deb
 164
 165 (Note: the packages supercollider-scel*.deb, supercollider-scvim*.deb,
 166 supercollider-sced*.deb, represent the different editor integrations:
 167 emacs, vim, gedit. You might not want to install all of those, but
 168 choose your preferred editor.)
 169
 170
 171 ------------------------------------------------------------------------
 172 running scsynth (standalone)
 173 ------------------------------------------------------------------------
 174
 175 run scsynth without options to get an option summary. don't forget to
 176 start jackd before trying to use scsynth. if you want to add
 177 directories to supercollider's search path or assign default jack
 178 ports, set up your environment as described below.
 179
 180 you can specify the number of jack input/output channels created with
 181 the options -i and -o, respectively.
 182
 183 the -H option can be used to specify a jack server to connect to and
 184 to set the jack client identifier. the format is either
 185
 186     <SERVER-NAME>:<CLIENT-NAME>
 187
 188 or just
 189
 190     <CLIENT-NAME>
 191
 192 when connecting to the default server.
 193
 194 ------------------------------------------------------------------------
 195 running sclang
 196 ------------------------------------------------------------------------
 197
 198 it is recommended to use sclang in combination with your preferred text
 199 editor out of emacs/vim/gedit. see the README files in `linux/*' for
 200 installation and usage. as an alternative you can simply run the
 201 `sclang' executable which will provide a readline-based interface.
 202
 203 sclang executes the startup file `~/.sclang.sc' after class library
 204 initialization. this file can contain statements to set up your
 205 supercollider environment, like setting default variables. an example can
 206 be found in `linux/examples/sclang.sc'.
 207
 208 you _have_ to have a directory `~/share/SuperCollider/'. This is where
 209 automatically a synthdefs directory is created. It is also the place
 210 to put Extensions to the class library, in a folder called Extensions.
 211
 212 the runtime directory is either the current working directory or the
 213 path specified with the `-d' option.
 214
 215 for advanced setups, sclang's compilation search path can be
 216 customized with a library configuration file. an example is provided
 217 in `linux/examples/sclang.cfg'; install it as `/etc/sclang.cfg' or
 218 `~/.sclang.cfg'. This config file is only needed when you want to
 219 _exclude_ directories from the class library. Otherwise (so in most cases)
 220 it is not needed.
 221
 222 ------------------------------------------------------------------------
 223 environment
 224 ------------------------------------------------------------------------
 225
 226 the jack audio driver interface is configured based on various
 227 environment variables:
 228
 229  * SC_JACK_DEFAULT_INPUTS comma separated list of jack ports that
 230    scsynth's inputs should connect to by default
 231
 232    $ export SC_JACK_DEFAULT_INPUTS="system:capture_1,system:capture_2"
 233
 234    in order to connect the first ports of one jack client, it is possible
 235    to specify only the client name
 236
 237    $ export SC_JACK_DEFAULT_INPUTS="system"
 238
 239  * SC_JACK_DEFAULT_OUTPUTS comma separated list of jack ports that
 240    scsynth's outputs should be connected to by default.
 241
 242    $ export SC_JACK_DEFAULT_OUTPUTS="system:playback_1,system:playback_2"
 243
 244    in order to connect the first ports of one jack client, it is possible
 245    to specify only the client name
 246
 247    $ export SC_JACK_DEFAULT_OUTPUTS="system"
 248
 249 two additional environment variables substitute directories for the default
 250 search path for plugins and synth definitions, respectively. directory
 251 names are separated by ':' as in the unix PATH variable:
 252
 253  * SC_PLUGIN_PATH, SC_SYNTHDEF_PATH
 254
 255    $ export SC_SYNTHDEF_PATH="./synthdefs:/home/sk/SuperCollider/synthdefs"
 256
 257 ------------------------------------------------------------------------
 258 documentation
 259 ------------------------------------------------------------------------
 260
 261 apart from the sites listed above, some more documentation links ...
 262
 263 a wiki for supercollider, set up by julian rohrhuber, is at
 264
 265     http://swiki.hfbk-hamburg.de/MusicTechnology/6
 266
 267 linux specific information can be found at
 268
 269     http://swiki.hfbk-hamburg.de/MusicTechnology/478
 270
 271 ------------------------------------------------------------------------
 272 reporting bugs
 273 ------------------------------------------------------------------------
 274
 275 please report bugs either to the sc-users or sc-dev mailing lists.
 276
 277 ------------------------------------------------------------------------
 278 contributors to this document
 279 ------------------------------------------------------------------------
 280
 281 stefan kersten <sk AT k-hornz DOT de>
 282 andi pieper
 283 maurizio umberto puxeddu
 284 rohan drape
 285 mario lang
 286 john yates
 287 nescivi (marije baalman)
 288 dan stowell
 289
 290 ------------------------------------------------------------------------
 291 outro
 292 ------------------------------------------------------------------------
 293
 294 thanks to james mccartney, for making this great piece of audio
 295 software publically and freely available.
 296
 297 ------------------------------------------------------------------------
 298 eof
 299 ------------------------------------------------------------------------
 300